---
title: 'Passwords'
description: 'Learn about password management features in Nile Auth'
---

## Features

- Password reset
- Password policies
- Password hashing and security

## Overview

With an SMTP provider configured on your database, users with emails can reset their passwords with a two step process. First, the users requests a link to be sent to their email address. The auth service creates a token (saved to the `auth.verification_tokens` table in your database), and sends it in an email. The token is valid for 4 hours by default.

## Installation

```sh
npm install @niledatabase/react @niledatabase/client
```

## Usage

`/user/reset-password`

```tsx
import { PasswordResetRequestForm } from './path/to/ResetForm';

const MyComponent = () => {
  return <PasswordResetRequestForm callbackUrl="/change-password" />;
};
```

<iframe
  src="https://storybook.thenile.dev/iframe.html?args=&globals=&id=reset-password-form--request-reset-password"
  width="100%"
  height="250px"
  className="rounded-md"
/>

Once the user clicks on the link, they will be redirected to your app and will be able to securely reset their password.

`/user/change-password`

```tsx
<PasswordResetForm
  defaultValues={{ email: 'user@example.com' }}
  onSuccess={() => console.log('Password updated successfully')}
  onError={(error) => console.error('Update failed', error)}
/>
```

<iframe
  src="https://storybook.thenile.dev/iframe.html?args=&globals=&id=reset-password-form--reset-password"
  width="100%"
  height="480px"
  className="rounded-md"
/>

## API

### `PasswordResetRequestForm` Props

| Name            | Type                                                    | Default                                            | Description                                               |
| --------------- | ------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `client`        | `QueryClient` _(optional)_                              | `undefined`                                        | React Query client instance.                              |
| `callbackUrl`   | `string` _(optional)_                                   | `undefined`                                        | The URL to redirect to after a successful password reset. |
| `defaultValues` | `object` _(optional)_                                   | `{ email: '', password: '', confirmPassword: '' }` | Default form values.                                      |
| `beforeMutate`  | `(data: AllowedAny) => AllowedAny` _(optional)_         | `undefined`                                        | Function executed before mutation to modify request data. |
| `onSuccess`     | `(res: Response) => void` _(optional)_                  | `undefined`                                        | Callback triggered on successful password reset.          |
| `onError`       | `(error: Error, data: AllowedAny) => void` _(optional)_ | `undefined`                                        | Callback triggered if the reset process fails.            |

### `PasswordResetForm` Props

| Name            | Type                                                    | Default                                            | Description                                               |
| --------------- | ------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `client`        | `QueryClient` _(optional)_                              | `undefined`                                        | React Query client instance.                              |
| `callbackUrl`   | `string` _(optional)_                                   | `undefined`                                        | The URL to redirect to after a successful password reset. |
| `defaultValues` | `object` _(optional)_                                   | `{ email: '', password: '', confirmPassword: '' }` | Default form values.                                      |
| `beforeMutate`  | `(data: AllowedAny) => AllowedAny` _(optional)_         | `undefined`                                        | Function executed before mutation to modify request data. |
| `onSuccess`     | `(res: Response) => void` _(optional)_                  | `undefined`                                        | Callback triggered on successful password reset.          |
| `onError`       | `(error: Error, data: AllowedAny) => void` _(optional)_ | `undefined`                                        | Callback triggered if the reset process fails.            |

## Internal Functionality

- Uses `useForm` from React Hook Form to handle form state.
- Calls `useResetPassword` with the provided email and password upon form submission.
- Implements password confirmation validation to ensure the user inputs matching passwords.
- Supports lifecycle hooks (`beforeMutate`, `onSuccess`, `onError`) for request customization.
- Disables the submit button if passwords do not match or required fields are missing.

## Related Topics

- [Email Templates](/auth/email/templates)
- [Email Verification](/auth/email/verification)
